\chapter{迭代器}\label{ch15}

\emph{It was the end of a very long day.}

\begin{flushright}
    ——Phil
\end{flushright}

一个\emph{迭代器(iterator)}可以产生一个值的序列，通常会使用一个循环来进行处理。Rust的标准库提供了遍历vector、字符串、哈希表和其他集合的迭代器，以及从一个输入流中产生若干行文本的迭代器、到达网络服务器的连接的迭代器、通过通道从其他线程接收到的值的迭代器，等等。当然，你可以实现自己的迭代器。Rust的\texttt{for}循环提供了一种自然地使用迭代器的语法，但迭代器自身也提供了丰富的方法集合用于映射、过滤、连接、收集等用途。

Rust的迭代器灵活、表达力强、高效。考虑下面的函数，它返回前\texttt{n}个正数的和（通常也被称为\emph{第n个三角数(nth triangle number)}：
\begin{minted}{Rust}
    fn triangle(n: i32) -> i32 {
        let mut sum = 0;
        for i in 1..=n {
            sum += i;
        }
        sum
    }
\end{minted}

表达式\texttt{1..=n}是一个\texttt{RangeInclusive<i32>}值。一个\texttt{RangeInclusive<i32>}是一个产生从起点到终点的所有整数的迭代器（包含起点和终点），因此你可以将它用作\texttt{for}循环的操作数来求\texttt{1}到\texttt{n}的和。

但迭代器也有一个\texttt{fold}方法，你可以使用它实现如下的等价定义：
\begin{minted}{Rust}
    fn triangle(n: i32) -> i32 {
        (1..=n).fold(0, |sum, item| sum + item)
    }
\end{minted}

以\texttt{0}作为起始的总和，\texttt{fold}会获取\texttt{1..=n}产生的每个值，然后用总和和产生的值调用闭包\texttt{|sum, item| sum + item}，每一次闭包的返回值就是新的总和。它最后返回的值就是\texttt{fold}自身返回的值——在这个例子中，就是整个序列的总和。如果你习惯使用\texttt{for}和\texttt{while}循环，那么这看起来会有些奇怪，但一旦你习惯了它，\texttt{fold}就是一个可读性强而简洁的替代方案。

这种写法是函数式编程语言的标准写法，这使得表达式有更强的表现力。但Rsut的迭代器是精心设计的，为了保证编译器可以把它们翻译成优秀的机器代码。在release构建模式下构建上面第二个定义时，Rust知道\texttt{fold}的定义，并且把它内联进\texttt{triangle}。然后，闭包\texttt{|sum, item| sum + item}也会被内联。最后，Rust会检查组合之后的代码，然后发现有一种更简单的方法计算从1到\texttt{n}的和：和总是等于\texttt{n * (n+1) / 2}。Rust会把\texttt{triangle}的整个函数体，包括循环、闭包等所有内容，变成一次乘法指令和一些其他的位运算。

这个例子恰巧可以转换成简单的算术，但在更复杂的使用中迭代器也可以表现的很好。它们是Rust提供灵活抽象的同时只有很小甚至没有开销的另一个例子。

在本章中，我们将会解释：
\begin{itemize}
    \item \texttt{Iterator}和\texttt{IntoIterator} trait，它们是Rust迭代器的基础
    \item 经典迭代器流水线的三个阶段：从初始的值创建一个迭代器；通过选择或处理值将一种迭代器变成另一种；消耗迭代器产生的值
    \item 如何为自己的类型实现迭代器
\end{itemize}

迭代器有很多方法，所以一旦你了解了大概的思路，就可以跳过那一节。但迭代器在Rust的习惯用法中非常普遍，熟悉这些随附的工具对掌握这门语言至关重要。

\section{\texttt{Iterator}与\texttt{IntoIterator trait}}\label{iter}

一个迭代器是任何实现了\texttt{std::iter::Iterator} trait的类型：
\begin{minted}{Rust}
    trait Iterator {
        type Item;
        fn next(&mut self) -> Option<Self::Item>;
        ... // 很多默认方法
    }
\end{minted}

\texttt{Item}是迭代器产生的值的类型。\texttt{next}方法可能返回\texttt{Some(v)}，其中\texttt{v}是迭代器的下一个值；或者返回\texttt{None}，表示已经到达序列的终点。这里我们省略了\texttt{Iterator}的很多默认方法；我们将在本章的剩余部分分别介绍它们。

如果某个类型有一种很自然的迭代方法，那么它可以实现\texttt{std::iter::IntoIterator}，它的\texttt{into\_iter}方法获取一个值并返回一个迭代它的迭代器：
\begin{minted}{Rust}
    trait IntoIterator where Self::IntoIter: Iterator<Item=Self::Item> {
        type Item;
        type IntoIter: Iterator;
        fn into_iter(self) -> Self::IntoIter;
    }
\end{minted}

\texttt{IntoIter}是迭代器本身的类型，\texttt{Item}是它产生的值的类型。我们称所有实现了\texttt{IntoIterator}\\
的类型为\emph{可迭代对象(iterable)}，因为你可以迭代它。

Rust的\texttt{for}循环将这些部分漂亮地组合在一起。为了迭代一个迭代器的元素，你可以写：
\begin{minted}{Rust}
    println!("There's:");
    let v = vec!["antimony", "arsenic", "alumium", "selenium"];

    for element in &v {
        println!("{}", element);
    }
\end{minted}

在底层，每一个\texttt{for}循环只是\texttt{IntoIterator}和\texttt{Iterator}的方法调用的缩写：
\begin{minted}{Rust}
    let mut iterator = (&v).into_iter();
    while let Some(element) = iterator.next() {
        println!("{}", element);
    }
\end{minted}

\texttt{for}循环使用了\texttt{IntoIterator::into\_iter}来把操作数\texttt{\&v}转换成一个迭代器，然后重复调用\texttt{Iterator::next}。每一次返回\texttt{Some(element)}时，\texttt{for}循环会执行循环体；如果它返回\texttt{None}，循环会终止。

考虑这个例子，其中有一些迭代器的术语：
\begin{itemize}
    \item 正如我们所说，\emph{迭代器(iterator)}是任何实现了\texttt{Iterator}的类型。
    \item \emph{可迭代对象(iterable)}是任何实现了\texttt{IntoIterator}的类型：你可以调用它的\texttt{into\_iter}方法获得一个迭代它的迭代器。这个例子中vector的引用\texttt{\&v}就是可迭代对象。
    \item 一个迭代器\emph{产生(produce)}值。
    \item 迭代器产生的值是\emph{item}。这里item是\texttt{"antimony", "arsenic"}，等等。
    \item 接受迭代器产生的item的代码是\emph{消费者(consumer)}。这个例子中，\texttt{for}循环就是消费者。
\end{itemize}

尽管\texttt{for}循环总是调用操作数的\texttt{into\_iter}，你也可以直接向\texttt{for}循环传递迭代器；例如，当你在\texttt{Range}上循环时就是这种情况。所有的迭代器都会自动实现\texttt{IntoIterator}，它们的\texttt{into\_iter}方法简单地返回迭代器自身。

如果在迭代器返回了\texttt{None}之后，你再调用它的\texttt{next}方法，那么\texttt{Iterator} trait并没有指定这种情况下该怎么做。大多数会再次返回\texttt{None}，但不是所有。（如果这导致了问题，\nameref{fuse}中介绍的\texttt{fuse}适配器可能会有帮助。）

\section{创建迭代器}
Rust标准库文档中详细解释了每种类型提供哪些种类的迭代器，但标准库提供了一些通用的约定来帮助你找到需要的迭代器。

\subsection{\texttt{iter}和\texttt{iter\_mut}方法}\label{IterMethod}
大多数集合类型提供\texttt{iter}和\texttt{iter\_mut}方法，它们返回一个迭代器，迭代器会产生每一个item的共享引用或可变引用。数组切片例如\texttt{\&[T]}和\texttt{\&mut [T]}也有\texttt{iter}和\texttt{iter\_mut}方法。除了使用\texttt{for}循环自动处理之外，这些方法是最常用的获得迭代器的方法：
\begin{minted}{Rust}
    let v = vec![4, 20, 12, 8, 6];
    let mut iterator = v.iter();
    assert_eq!(iterator.next(), Some(&4));
    assert_eq!(iterator.next(), Some(&20));
    assert_eq!(iterator.next(), Some(&12));
    assert_eq!(iterator.next(), Some(&8));
    assert_eq!(iterator.next(), Some(&6));
    assert_eq!(iterator.next(), None);
\end{minted}

这个迭代器的item类型是\texttt{\&i32}：每一次调用\texttt{next}都会产生下一个元素的引用，直到到达vector的终点。

每一个类型都可以实现\texttt{iter}和\texttt{iter\_mut}，不管它们的实现是否有意义。\texttt{std::path::Path}的\\
\texttt{iter}返回的迭代器一次产生路径的一段：
\begin{minted}{Rust}
    use std::ffi::OsStr;
    use std::path::Path;

    let path = Path::new("C:/Users/JimB/Downloads/Fedora.iso");
    let mut iterator = path.iter();
    assert_eq!(iterator.next(), Some(OsStr::new("C:")));
    assert_eq!(iterator.next(), Some(OsStr::new("Users")));
    assert_eq!(iterator.next(), Some(OsStr::new("JimB")));
    ...
\end{minted}

这个迭代器的item类型是\texttt{\&std::ffi::OsStr}，它是操作系统调用接受的一种字符串类型的引用切片。

如果某个类型有不止一种迭代方式，那么这个类型通常为每种遍历方式提供特定的方法，因为这时普通的\texttt{iter}方法将会导致歧义。例如，\texttt{\&str}字符串切片类型没有\texttt{iter}方法。作为替代，假设\texttt{s}是\texttt{\&str}，那么\texttt{s.bytes()}返回一个产生\texttt{s}的每个字节的迭代器，而\texttt{s.chars()}会以UTF-8编码解析它的内容，然后产生每一个Unicode字符。

\subsection{\texttt{IntoIterator}实现}\label{IntoIter}
当一个类型实现了\texttt{IntoIterator}之后，你可以自己调用它的\texttt{into\_iter}方法，正如\texttt{for}循环做的一样：
\begin{minted}{Rust}
    // 你通常应该使用HashSet，但它的迭代顺序是不确定的，
    // 因此这个例子中BTreeSet会工作得更好。
    use std::collections::BTreeSet;
    let mut favorites = BTreeSet::new();
    favorites.insert("Lucy in the Sky With Diamonds".to_string());
    favorites.insert("Liebesträume No. 3".to_string());

    let mut it = favorites.into_iter();
    assert_eq!(it.next(), Some("Liebesträume No. 3".to_string()));
    assert_eq!(it.next(), Some("Lucy in the Sky With Diamonds".to_string()));
    assert_eq!(it.next(), None);
\end{minted}

大多数集合实际上都提供了好几个\texttt{IntoIterator}的实现，分别是为共享引用(\texttt{\&T})、可变引用(\texttt{\&mut T})、移动(\texttt{T})提供的实现：
\begin{itemize}
    \item 给定一个集合的\emph{共享引用(shared reference)}，\texttt{into\_iter}返回一个产生item的共享引用的迭代器。例如，在上面的代码中，\texttt{(\&favorites).into\_iter()}将会返回一个\texttt{Item}类型是\texttt{\&String}的迭代器。
    \item 给定一个集合的\emph{可变引用(mutable reference)}，\texttt{into\_iter}返回一个产生item的可变引用的迭代器。例如，如果\texttt{vector}是\texttt{Vec<String>}，那么\texttt{(\&mut vector).into\_iter()}将返回一个\texttt{Item}类型是\texttt{\&mut String}的迭代器。
    \item 当集合\emph{以值}传递时，\texttt{into\_iter}返回一个获取集合所有权并返回item自身的迭代器；item的所有权从集合移动到消费者，原来的集合在这个过程中被消耗。例如，上面代码中的\texttt{favorites.into\_iter()}会返回一个产生每个字符串值的迭代器；消费者会接受每个字符串的所有权。当迭代器被drop时，\texttt{BTreeSet}中剩余的所有元素也都会被drop，并且集合会变为未初始化。
\end{itemize}

因为\texttt{for}循环会对操作数调用\texttt{IntoIterator::into\_iter}，这三种实现会导致有下面三种迭代方式：迭代集合的共享引用、迭代集合的可变引用、或者消耗集合并获取它的元素的所有权：
\begin{minted}{Rust}
    for element in &collection { ... }
    for element in &mut collection { ... }
    for element in collection { ... }
\end{minted}

这三种写法会调用上面列出的\texttt{IntoIterator}实现之一。

并不是每个类型都提供了全部这三种实现。例如，\texttt{HashSet}、\texttt{BTreeSet}、\texttt{BinaryHeap}没有实现可变引用的\texttt{IntoIterator}，因为修改它们的元素可能会破坏类型的不变量：修改后的值可能会有不同的哈希值、或者和它的邻居的顺序关系会改变，因此修改元素会导致它们被放在错误的地方。其他的类型支持可变性，但只支持部分。例如，\texttt{HashMap}和\texttt{BTreeMap}产生表项的value的可变引用，以及key的共享引用，原因和上面类似。

一般的准则是迭代应该高效和可预测，因此Rust不提供开销很大或者可能展现出令人惊讶的行为的实现（例如，重新哈希被修改的\texttt{HashSet}条目并因此导致之后的迭代中可能再次遇到它们）。

切片实现了三种\texttt{IntoIterator}变体中的两个；因为它们并不拥有自己引用的元素，因此没有“以值”的实现。作为代替，\texttt{\&[T]}和\texttt{\&mut [T]}的\texttt{into\_iter}返回一个产生共享引用和可变引用的迭代器。如果你把底层切片类型\texttt{[T]}想象成一种集合，那么它就落入了之前的模式。

你可能已经注意到前两种\texttt{IntoIterator}的变体产生共享和可变的引用，这和调用\texttt{iter}或者\texttt{iter\_mut}是等价的。为什么Rust同时提供两者？

\texttt{IntoIterator}使\texttt{for}循环能正常工作，因此它显然是必要的。但当你不使用\texttt{for}循环时，使用\texttt{favorites.iter()}比\texttt{(\&favorites).into\_iter()}更加清晰。你可能会频繁需要以共享引用迭代，因此\texttt{iter}和\texttt{iter\_mut}也很有用。

\texttt{IntoIterator}在泛型代码中也很有用：你可以使用一个约束例如\texttt{T: IntoIterator}来限制类型参数\texttt{T}必须是可以迭代的类型。或者，你可以写\texttt{T: IntoIterator<Item=U>}来进一步要求迭代会产生\texttt{U}类型的值。例如，这个函数打印出任何item可以用\texttt{"\{:?\}"}格式打印的可迭代对象：
\begin{minted}{Rust}
    use std::fmt::Debug;

    fn dump<T, U>(t: T)
        where T: IntoIterator<Item=U>,
              U: Debug
    {
        for u in t {
            println!("{:?}", u);
        }
    }
\end{minted}
你不能在这个泛型函数中使用\texttt{iter}或者\texttt{iter\_mut}，因为它们不是任何trait的方法，大多数可迭代类型只是恰好有这两个方法。

\subsection{\texttt{from\_fn}和\texttt{successors}}

一个简单而通用的产生一个值序列的方式是提供一个返回它们的闭包。

给定一个返回\texttt{Option<T>}的函数，\texttt{std::iter::from\_fn}返回一个迭代器，它简单地调用那个函数来产生item。例如：
\begin{minted}{Rust}
    use rand::random;   // 在Cargo.toml中添加依赖：rand = "0.7"
    use std::iter::from_fn;
    // 产生1000个随机数，在[0, 1]之间均匀分布。
    // （这并不是你想在`rand_distr` crate中找到的分布，
    // 但你可以很容易地自己实现它）
    let lengths: Vec<f64> =
        from_fn(|| Some((random::<f64>() - random::<f64>()).abs()))
        .take(1000)
        .collect();
\end{minted}

这里调用了\texttt{from\_fn}来制作一个产生随机数的迭代器。因为这个迭代器总是返回\texttt{Some}，因此这个序列永远不会终止，但我们调用了\texttt{take(1000)}来限制只要前1000个元素。然后\texttt{collect}从最后的迭代器构建一个vector。这是一种高效地构建初始化的vector的方式。我们将在本章稍后的\nameref{BuildColl}中介绍为什么。

如果每一个item都依赖上一个，那么\texttt{std::iter::successors}函数可以漂亮地工作。你需要提供一个初始item和一个函数，这个函数要获取上一个item并返回下一个item的\texttt{Option}。如果返回\texttt{None}，那么迭代终止。例如，这里有另一种编写\hyperref[ch02]{第2章}中的曼德勃罗集绘制器的\texttt{escape\_time}函数的方法：
\begin{minted}{Rust}
    use num::Complex;
    use std::iter::successors;

    fn escape_time(c: Complex<f64>, limit: usize) -> Option<usize> {
        let zero = Complex { re: 0.0, im: 0.0 };
        successors(Some(zero), |&z| { Some(z * z + c) })
            .take(limit)
            .enumerate()
            .find(|(_i, z)| z.norm_sqr() > 4.0)
            .map(|(i, _z)| i)
    }
\end{minted}

从zero开始，\texttt{successors}调用通过重复平方再加上参数\texttt{c}来产生一个复平面上点的序列。当绘制曼德勃罗集时，我们希望知道这个序列会一直在原点附近还是远离原点。\texttt{take(limit)}调用设置了序列长度的限制，\texttt{enumerate}为每一个点加上一个序号、把每个点\texttt{z}变为元组\texttt{(i, z)}。然后我们使用\texttt{find}来查找第一个离原点足够远可以逃离的点。如果存在这样的点，\texttt{find}方法返回一个\texttt{Option::Some((i, z))}，否则返回\texttt{None}。\texttt{Option::map}的调用会把\texttt{Some((i, z))}变为\texttt{Some(i)}，但不会改变\texttt{None}：这正是我们想要的返回值。

\texttt{from\_fn}和\texttt{successors}都接受\texttt{FnMut}闭包，因此你的闭包可以捕获并修改作用域中的变量。例如，这个\texttt{fibonacci}函数使用一个\texttt{move}闭包来捕获一个变量并使用它作为运行状态：
\begin{minted}{Rust}
    fn fibonacci() -> impl Iterator<Item=usize> {
        let mut state = (0, 1);
        std::iter::from_fn(move || {
            state = (state.1, state.0 + state.1);
            Some(state.0)
        })
    }

    assert_eq!(fibonacci().take(8).collect::<Vec<_>>(),
               vec![1, 1, 2, 3, 5, 8, 13, 21]);
\end{minted}

注意：\texttt{from\_fn}和\texttt{successors}方法非常灵活，你可以把对迭代器的任何使用变成对其中一个的单一调用，通过复杂的闭包来获得你需要的行为。但这样做会忽略迭代器提供的表明数据流动和使用标准名称用于通用模式的能力。在你使用这两个函数之前请确保你已经熟悉了本章中的其他迭代器方法，它们通常是更好的完成工作的方式。

\subsection{\texttt{drain}方法}
很多集合类型提供一个\texttt{drain}方法来获取集合的可变引用，并返回一个迭代器把每个元素的所有权传递给消费者。然而，和\texttt{into\_iter()}以值获取集合并消耗它不同，\texttt{drain}借用一个集合的可变引用，并且当迭代器被drop时，它会移除集合中剩余的所有元素，让集合变为空。

对于可以用范围索引的类型，例如\texttt{String}、vector、\texttt{VecDeque}，\texttt{drain}方法获取一个要移除的元素的范围，而不是消耗整个序列：
\begin{minted}{Rust}
    use std::iter::FromIterator;

    let mut outer = "Earth".to_string();
    let inner = String::from_iter(outer.dran(1..4));

    assert_eq!(outer, "Eh");
    assert_eq!(inner, "art");
\end{minted}

如果你确实要消耗整个序列，使用整个范围\texttt{..}作为参数。

\subsection{其他迭代器源}
上面的几节基本都是关于像vector和\texttt{HashMap}这样的集合类型的，但标准库中还有很多其他类型支持迭代。\hyperref[t15-1]{表15-1}总结了一些有趣的类型，但还有更多没有列出。我们将在专门介绍特定类型的章节（即\hyperref[ch16]{第16章}、\hyperref[ch17]{第17章}、\hyperref[ch18]{第18章}）中详细介绍其中的一些方法。

\begin{longtable}{p{0.26\textwidth}p{0.26\textwidth}p{0.4\textwidth}}
    \caption{标准库中的其他迭代器}
    \label{t15-1}\\
    \hline
    \textbf{类型或trait} & \textbf{表达式} & \textbf{注意} \\
    \hline
    \multirow{2}{*}{\texttt{std::ops::Range}} & \texttt{1..10} & 端点必须是整数才能迭代。包括起点但不包括终点。 \\
    & \texttt{(1..10).step\_by(2)} \cellcolor{tablecolor} & 产生1，3，5，7，9。 \cellcolor{tablecolor} \\
    \hline
    \texttt{std::ops::RangeFrom} & \texttt{1..} & 无限迭代。起点必须是整数。当值到达了这种类型的极限时可能会panic或者溢出。 \\
    \hline
    \rowcolor{tablecolor}
    \texttt{std::ops:: RangeInclusive} & \texttt{1..=10} & 类似\texttt{Range}，但包括终点值。 \\
    \hline
    \texttt{Option<T>} & \texttt{Some(10).iter()} & 类似于一个长度为0(\texttt{None})或1的vector(\texttt{Some(v)})。 \\
    \hline
    \rowcolor{tablecolor}
    \texttt{Result<T, E>} & \texttt{Ok("blah").iter()} & 类似于\texttt{Option}，产生\texttt{Ok}值。 \\
    \hline
    \multirow{7}{*}{\texttt{Vec<T>, \&[T]}} & \texttt{v.windows(16)} & 从左到右产生重叠的、连续的给定长度的切片。 \\
    & \texttt{v.chunks(16)} \cellcolor{tablecolor} & 从左到右产生非重叠的、连续的给定长度的切片。 \cellcolor{tablecolor} \\
    & \texttt{v.chunks\_mut(1024)} & 类似\texttt{chunks}，不过切片是可变的。 \\
    & \texttt{v.split(|byte| byte \& 1 != 0)} \cellcolor{tablecolor} & 产生被满足条件的元素分隔的切片。 \cellcolor{tablecolor} \\
    & \texttt{v.split\_mut(...)} & 同上，但产生可变切片。 \\
    & \texttt{v.rsplit(...)} \cellcolor{tablecolor} & 类似\texttt{split}，但从右向左产生切片。 \cellcolor{tablecolor} \\
    & \texttt{v.splitn(n, ...)} & 类似\texttt{split}，但最多产生\texttt{n}个切片。 \\
    \hline
    \multirow{5}{*}{\texttt{String, \&str}} & \texttt{s.bytes()} \cellcolor{tablecolor} & 产生UTF-8字符串的字节。 \cellcolor{tablecolor} \\
    & \texttt{s.chars()} & 产生UTF-8字符串的\texttt{char}。 \\
    & \texttt{s.split\_whitespace()} \cellcolor{tablecolor} & 以空格分隔字符串，产生非空字符们的切片。 \cellcolor{tablecolor} \\
    & \texttt{s.lines()} & 产生字符串的每一行的切片。 \\
    & \texttt{s.split('/')} \cellcolor{tablecolor} & 用给定的模式分隔字符串，产生每两个匹配之间的内容的切片。模式可以是字符、字符串或者闭包。\cellcolor{tablecolor} \\
    \hline
    \multirow{5}{*}{\shortstack[l]{\texttt{std::collections::}\\\texttt{HashMap, std::}\\\texttt{collections::BTreeMap}}} & \texttt{s.matches(char:: is\_numeric)} & 产生匹配给定模式的切片。 \\
    & \texttt{map.keys(), map.values()} \cellcolor{tablecolor} & 产生map的key或value的共享引用。 \cellcolor{tablecolor} \\
    & \texttt{map.values\_mut()} & 产生条目的value的可变引用。 \\
    \hline
    \multirow{3}{*}{\shortstack[l]{\texttt{std::collections::}\\\texttt{HashSet, std::}\\\texttt{collections::BTreeSet}}} & \texttt{set1.union(set2)} \cellcolor{tablecolor} & 产生\texttt{set1}和\texttt{set2}的并集的元素的共享引用。 \cellcolor{tablecolor} \\
    & \texttt{set1.intersection(set2)} & 产生\texttt{set1}和\texttt{set2}的交集的元素的共享引用。 \\
    \hline
    \rowcolor{tablecolor}
    \texttt{std::sync::mpsc:: Receiver} & \texttt{rev.iter()} & 产生另一个线程通过相应的\texttt{Sender}发送的值。 \\
    \hline
    \multirow{2}{*}{\texttt{std::io::Read}} & \texttt{stream.bytes()} & 产生来自I/O流的字节。 \\
    & \texttt{stream.chars()} \cellcolor{tablecolor} & 以UTF-8解析流，产生\texttt{char}。 \cellcolor{tablecolor} \\
    \hline
    \multirow{2}{*}{\texttt{std::io::BufRead}} & \texttt{bufstream.lines()} & 以UTF-8解析流，产生\texttt{String}。 \\
    & \texttt{bufstream.split(0)} \cellcolor{tablecolor} & 用给定的字节切分流，产生\texttt{Vec<u8>}缓冲区。 \cellcolor{tablecolor} \\
    \hline
    \texttt{std::fs::ReadDir} & \texttt{std::fs::read\_dir(path)} & 产生目录项。 \\
    \hline
    \rowcolor{tablecolor}
    \texttt{std::net::TcpListener} & \texttt{listener.incoming()} & 产生到来的网络连接。 \\
    \hline
    \multirow{3}{*}{自由函数} & \texttt{std::iter::empty()} & 立即返回\texttt{None}。 \\
    & \texttt{std::iter::once(5)} \cellcolor{tablecolor} & 产生给定值然后结束。 \cellcolor{tablecolor} \\
    & \texttt{std::iter::repeat("\#9")} & 永远产生给定值。 \\
    \hline
\end{longtable}

\section{迭代器适配器}

一旦你得到了一个迭代器，\texttt{Iterator} trait还提供了广泛的\emph{适配器方法(adapter method)}，或者简称为\emph{适配器(adapter)}，它们消耗一个迭代器然后构建一个新的迭代器。为了展示适配器如何工作，我们将从两个最流行的适配器\texttt{map}和\texttt{filter}开始。然后我们会介绍其他的适配器，它们包括几乎所有你能想到的把一个序列的值变成另一个序列的方法：截断、跳过、组合、反向、连接、重复，等等。

\subsection{\texttt{map}和\texttt{filter}}
\texttt{Iterator} trait的\texttt{map}适配器让你通过对每一个item应用一个闭包来产生新迭代器。\texttt{filter}迭代器让你通过一个闭包决定保留哪些item丢弃哪些item，以此过滤迭代器中的某些item。

例如，假设你在迭代文本的每一行，并且想省略每一行的前导和尾部的空格。标准库的\texttt{str::trim}方法排除一个\texttt{\&str}中的前导和尾部空格，返回一个新的借用\texttt{\&str}。你可以使用\texttt{map}适配器来对迭代器返回的每一行应用\texttt{str::trim}：
\begin{minted}{Rust}
    let text = "  ponies \n   giraffes\niguanas  \nsquid".to_string();
    let v: Vec<&str> = text.lines()
        .map(str::trim)
        .collect();
    assert_eq!(v, ["ponies", "giraffes", "iguanas", "squid"]);
\end{minted}

\texttt{text.lines()}调用返回一个产生每一行的迭代器。对迭代器调用\texttt{map}返回第二个迭代器，它会对每一行调用\texttt{str::trim}，然后将结果作为产生的item。最后，\texttt{collect}把所有item聚集成一个vector。

当然，\texttt{map}返回的迭代器，本身也可以继续适配。如果你想从结果中排除“iguanas”，你可以像下面这样写：
\begin{minted}{Rust}
    let text = "  ponies \n   giraffes\niguanas  \nsquid".to_string();
    let v: Vec<&str> = text.lines()
        .map(str::trim)
        .filter(|s| *s != "iguanas")
        .collect();
    assert_eq!(v, ["ponies", "giraffes", "squid"]);
\end{minted}

这里\texttt{filter}返回第三个迭代器，只有当\texttt{map}返回的迭代器产生的item调用闭包\texttt{|s| *s != "iguanas"}后返回\texttt{true}时，第三个迭代器才会产生这个item。一个这样的迭代器适配器链就像Unix shell中的管道：每一个适配器都有单个功能，很容易就能看清楚值的序列是如何从左到右转换的。

这两个适配器的签名如下：
\begin{minted}{Rust}
    fn map<B, F>(self, f: F) -> impl Iterator<Item=B>
        where Self: Sized, F: FnMut(Self::Item) -> B;

    fn filter<P>(self, predicate: P) -> impl Iterator<Item=Self::Item>
        where Self: Sized, P: FnMut(&Self::Item) -> bool;
\end{minted}

在标准库中，\texttt{map}和\texttt{filter}实际上返回特定的不透明\texttt{struct}类型，分别是\texttt{std::iter::Map}\\
和\texttt{std::iter::Filter}。然而它们的名字提供的信息量很少，所以在本书中我们将用\texttt{-> impl Iterator<Item=...>}来代替，因为它们能告诉我们我们实际想要知道的信息：这个方法返回一个产生给定类型的item的\texttt{Iterator}。

因为大多数适配器以值获取\texttt{self}，所以它们需要\texttt{Self}是\texttt{Sized}（大多数迭代器都是）。

\texttt{map}迭代器会依次把所有item以值传递给闭包，然后把结果返回给消费者。\texttt{filter}迭代器以共享引用把所有的item传递给闭包，保留选中的item的所有权，然后把它们传递给消费者。这就是为什么上面的例子要先解引用\texttt{s}再和\texttt{"iguanas"}比较：\texttt{filter}迭代器的item类型是\texttt{\&str}，所以闭包参数的类型是\texttt{\&\&str}。

有关迭代器适配器有两个重要的点。

首先，在一个迭代器上调用适配器并不会消耗任何item，它只会返回一个新的迭代器，这个迭代器按需处理第一个迭代器产生的item来产生自己的item。在一个适配器链中，唯一会消耗item的方式就是对最后的迭代器调用\texttt{next}。

因此在我们之前的例子中，\texttt{text.lines()}方法调用本身并不从字符串解析行，它只是返回一个迭代器，只有当需要的时候这个迭代器\emph{才会}解析行。类似的，\texttt{map}和\texttt{filter}只是返回需要时\emph{才会}映射或过滤的新迭代器。在最后一个\texttt{collect}开始对\texttt{filter}迭代器调用\texttt{next}之前，将不会有任何计算发生。

当你的适配器有副作用时这一点尤其重要。例如，下面的代码什么也不打印：
\begin{minted}{Rust}
    ["earth", "water", "air", "fire"]
        .iter().map(|elt| println!("{}", elt));
\end{minted}

\texttt{iter}调用返回一个迭代数组元素的迭代器，\texttt{map}调用返回第二个迭代器，第二个迭代器对第一个迭代器产生的每个值调用闭包。但如果整个链中没有要求产生值的操作，那么将不会有\texttt{next}方法被调用。事实上，Rust会警告你这种情况：
\begin{minted}{text}
    warning: unused `std::iter::Map` that must be used
      |
    7 | /     ["earth", "water", "air", "fire"]
    8 | |          .iter().map(|elt| println!("{}", elt));
      | |________________________________________________^
      |
      = note: iterators are lazy and do nothing unless consumed
\end{minted}

错误消息中的术语“lazy”并不是贬义词；它只是对任何直到需要时才进行计算的机制的一种称呼。迭代器应该做最少的必要的工作来满足\texttt{next}调用是Rust的习惯；在这个例子中，并没有\texttt{next}调用，因此不会有任何计算发生。

第二个重要的点是迭代器适配器是0成本抽象。因为\texttt{map}、\texttt{filter}以及它们的同伴都是泛型的，将它们用于迭代器会生成特定迭代器类型的代码。这意味着Rust有足够的信息把每一个迭代器\texttt{next}方法内联到消费者中，然后把整个操作作为一个单元翻译为机器码。因此我们上面展示的\texttt{lines/map/filter}迭代器链和你手写的代码一样高效：
\begin{minted}{Rust}
    for line in text.lines() {
        let line = line.trim();
        if line != "iguanas" {
            v.push(line);
        }
    }
\end{minted}

这一节剩余的部分将介绍\texttt{Iterator} trait可用的适配器。

\subsection{\texttt{filter\_map}和\texttt{flat\_map}}
\texttt{map}适配器适用于一个输入item产生一个输出item的情况。但如果你想删除迭代中的某些item而不是处理它们，或者想将一个item替换成0个或更多的item时该怎么做呢？\texttt{filter\_map}和\texttt{flat\_map}适配器赋予了你这种灵活性。

\texttt{filter\_map}适配器类似于\texttt{map}，除了它的闭包要么将一个item转换成一个新的item（和\texttt{map}一样），要么从迭代中丢弃这个item。因此，它有些像\texttt{filter}和\texttt{map}的结合。它的签名如下：
\begin{minted}{Rust}
    fn filter_map<B, F>(self, f: F) -> impl Iterator<Item=B>
        where Self: Sized, F: FnMut(Self::Item) -> Option<B>;
\end{minted}

除了闭包返回\texttt{Option<B>}之外，而不是\texttt{B}之外，它和\texttt{map}的签名是一样的。当闭包返回\texttt{None}时，这个item会从迭代器中丢弃；当它返回\texttt{Some(b)}时，\texttt{b}就是\texttt{filter\_map}迭代器产生的下一个item。

例如，假设你想扫描一个字符串中空格分隔的单词，找到其中可以被解析为数字的并处理它，然后丢弃其他单词。那你可以写：
\begin{minted}{Rust}
    use std::str::FromStr;

    let text = "1\nfrond .25 289\n3.1415 estuary\n");
    for number in text
        .split_whitespace()
        .filter_map(|w| f64::from_str(w).ok())
    {
        println!("{:4.2}", number.sqrt());
    }
\end{minted}
打印结果如下：
\begin{minted}{text}
    1.00
    0.50
    17.00
    1.77
\end{minted}

传给\texttt{filter\_map}的闭包尝试对每一个空格分隔的切片调用\texttt{f64::from\_str}。这会返回一个\texttt{Result<f64, ParseFloatError>}，它的\texttt{.ok()}返回一个\texttt{Option<f64>}：解析错误时是\texttt{None}，解析成功时是\texttt{Some(v)}。\texttt{filter\_map}迭代器丢弃所有的\texttt{None}值，然后对每一个\texttt{Some(v)}产生值\texttt{v}。

但为什么要将\texttt{map}和\texttt{filter}融合成这样的单个操作，而不是直接使用两个适配器？\texttt{filter\_map}适配器适用于刚刚展示过的这种情况，即只有实际尝试处理过item才知道应不应该包含这个item的情况。你可以只用\texttt{filter}和\texttt{map}做到同样的事情，但这样会很笨拙：
\begin{minted}{Rust}
    text.split_whitespace()
        .map(|w| f64::from_str(w))
        .filter(|r| r.is_ok())
        .map(|r| r.unwrap())
\end{minted}

你可以认为\texttt{flat\_map}适配器和\texttt{map}、\texttt{filter\_map}是同一类的，区别在于现在闭包不是只能返回一个item(\texttt{map})或者0或1个item(\texttt{filter\_map})，而是可以返回任意数量的item。\texttt{flat\_map}迭代器产生闭包返回的序列的串联。

\texttt{flat\_map}的签名如下：
\begin{minted}{Rust}
    fn flat_map<U, F>(self, f: F) -> impl Iterator<Item=U::Item>
        where F: FnMut(Self::Item) -> U, U: IntoIterator;
\end{minted}
传给\texttt{flat\_map}的闭包必须返回一个可迭代对象，但任何类型的可迭代对象都可以。\footnote{事实上，因为\texttt{Option}也是一个可迭代对象，行为就像一个有0个或者1个item的序列。所以假设\texttt{closure}返回一个\texttt{Option<T>}，那么\texttt{iterator.filter\_map(closure)}等价于\texttt{iterator.flat\_map(closure)}。}

例如，假设我们有一个把国家映射到主要城市的表。给定一个国家的列表，那我们怎么遍历它们的主要城市？
\begin{minted}{Rust}
    use std::collections::HashMap;

    let mut major_cities = HashMap::new();
    major_cities.insert("Japan", vec!["Tokyo", "Kyoto"]);
    major_cities.insert("The United States", vec!["Portland", "Nashville"]);
    major_cities.insert("Brazil", vec!["São Paulo", "Brasilia"]);
    major_cities.insert("Kenya", vec!["Nairobi", "Mombasa"]);
    major_cities.insert("The Netherlands", vec!["Amsterdam", "Utrecht"]);

    let countries = ["Japan", "Brazil", "Kenya"];

    for &city in countries.iter().flat_map(|country| &major_cities[country]) {
        println!("{}", city);
    }
\end{minted}
这会打印出下列内容：
\begin{minted}{text}
    Tokyo
    Kyoto
    São Paulo
    Brasilia
    Nairobi
    Mombasa
\end{minted}

这段代码的意思是，对于每一个国家，我们都获取它的城市的vector，然后将所有vector连接成单个序列，然后打印出来。

但记住迭代是惰性的：只有当\texttt{for}循环调用了\texttt{flat\_map}迭代器的\texttt{next}方法时才会开始计算。完全连接的序列从来不会在内存中构造。实际上，这里只有一个小的状态机，对于每一个城市迭代器，一次打印一个item，直到耗尽，然后为下一个国家产生一个新的城市迭代器。效果就类似于嵌套的循环，但被打包用作迭代器。

\subsection{\texttt{flatten}}
\texttt{flatten}适配器把迭代器的item连接起来，假设每一个item都是可迭代对象：
\begin{minted}{Rust}
    use std::collections::BTreeMap;

    // 把城市映射到公园的表：每一个value都是一个vector。
    let mut parks = BTreeMap::new();
    parks.insert("Portland",  vec!["Mt. Tabor Park", "Forest Park"]);
    parks.insert("Kyoto",     vec!["Tadasu-no-Mori Forest", "Maruyama Koen"]);
    parks.insert("Nashville", vec!["Percy Warner Park", "Dargon Park"]);

    // 构建一个所有公园的vector。`values`返回一个产生vector的迭代器，
    // 然后`flatten`按顺序产生每一个vector的元素。
    let all_parks: Vec<_> = parks.values().flatten().cloned().collect();

    assert_eq!(all_parks,
               vec!["Tadasu-no-Mori Forest", "Maruyama Koen", "Percy Warner Park", 
                    "Dragon Park", "Mt. Tabor Park", "Forest Park"]);
\end{minted}

“flatten”这个名字来自于想象把一个两层的结构压扁成一层的结构：\texttt{BTreeMap}和它的\texttt{Vec}的元素被压成一个产生所有元素的迭代器。

\texttt{flatten}的签名如下：
\begin{minted}{Rust}
    fn flatten(self) -> impl Iterator<Item=Self::Item::Item>
        where Self::Item: IntoIterator;
\end{minted}

换句话说，迭代器的item自身必须实现了\texttt{IntoIterator}，这样它才是一个高效的序列的序列。\texttt{flatten}方法返回一个这些序列连接之后的迭代器。当然，这都是惰性完成的，只有当我们迭代完了一个序列才会从\texttt{self}产生一个新的item。

\texttt{flatten}方法还有一些令人惊讶的用法。如果你有一个\texttt{Vec<Option<...>>}并且你想只迭代其中的\texttt{Some}值，那么\texttt{flatten}可以漂亮地工作：
\begin{minted}{Rust}
    assert_eq!(vec![None, Some("day"), None, Some("one")]
               .into_iter()
               .flatten()
               .collect::<Vec<_>>(),
               vec!["day", "one"]);
\end{minted}

这种方式可以工作是因为\texttt{Option}自身实现了\texttt{IntoIterator}，代表一个有0或1个元素的序列。\texttt{None}元素对迭代过程没有贡献，而每一个\texttt{Some}元素贡献一个值。类似的，你可以使用\texttt{flatten}来迭代\texttt{Option<Vec<...>>}：\texttt{None}和空vector的行为一样。

\texttt{Result}也实现了\texttt{IntoIterator}，\texttt{Err}时代表一个空的序列，因此对一个产生\texttt{Result}值的迭代器调用\texttt{flatten}可以高效地排除所有\texttt{Err}，产生一个解包之后的成功值的序列。我们不推荐在代码中忽略错误，但当用户知道自己在做什么时这是一个巧妙的技巧。

当你需要\texttt{flatten}时你可能会发现你真正需要的是\texttt{flat\_map}。例如，标准库的\\
\texttt{str::to\_uppercase}方法把一个字符串转换成大写，工作方式类似于下面的代码：
\begin{minted}{Rust}
    fn to_uppercase(&self) -> String {
        self.chars()
            .map(char::to_uppercase)
            .flatten() // 有更好的方式
            .collect()
    }
\end{minted}

这里必须使用\texttt{flatten}的原因是\texttt{char::to\_uppercase()}并不是返回单个字符，而是返回一个可能产生一个或更多字符的迭代器。map调用会返回一个产生字符迭代器的迭代器，\texttt{flatten}将它们拼接在一起，因此我们最后可以调用\texttt{collect}把它们转换为一个\texttt{String}。

但这种\texttt{map}和\texttt{flatten}的组合使用如此普遍，以至于\texttt{Iterator}提供了\texttt{flat\_map}适配器来处理这种情况。（事实上，\texttt{flat\_map}比\texttt{flatten}更先加入标准库。）因此上面的代码可以写成：
\begin{minted}{Rust}
    fn to_uppercase(&self) -> String {
        self.chars()
            .flat_map(char::to_uppercase)
            .collect()
    }
\end{minted}

\subsection{\texttt{take}和\texttt{take\_while}}
\texttt{Iterator} trait的\texttt{take}和\texttt{take\_while}适配器让你可以在迭代了一定的次数或者当一个闭包决定截断时停止迭代。它们的签名如下：
\begin{minted}{Rust}
    fn take(self, n: usize) -> impl Iterator<Item=Self::Item>
        where Self: Sized;
    
    fn take_while<P>(self, predicate: P) -> impl Iterator<Item=Self::Item>
        where Self: Sized, P: FnMut(&Self::Item) -> bool;
\end{minted}

这两个方法都获取一个迭代器的所有权，返回一个新的迭代器，新的迭代器从第一个item开始迭代，可能会提前终止序列。在产生最多\texttt{n}个item之后\texttt{take}迭代器会返回\texttt{None}。\texttt{take\_while}迭代器对每个item引用\texttt{predicate}，当有一个item使\texttt{predicate}返回\texttt{false}时返回\texttt{None}，之后对\texttt{next}的调用也都会返回\texttt{None}。

例如，给定一个电子邮件的消息，其中消息头和消息主体用一个空行分隔，那么你就可以使用\texttt{take\_while}来只迭代器消息头：
\begin{minted}{Rust}
    let message = "To: jimb\r\n\
                   From: superego <editor@oreilly.com>\r\n\
                   \r\n\
                   Did you get any writing done today?\r\n\
                   When will you stop wasting time plotting fractals?\r\n";
    for header in message.lines().take_while(|l| !l.is_empty()) {
        println!("{}", header);
    }
\end{minted}

回顾\nameref{StrLiteral}，当字符串行以反斜杠结尾时，Rust并不会把下一行的缩进包含进字符串里，因此这个字符串中的任何一行都没有前导空格。这意味着\texttt{message}的第三行是空行。\texttt{take\_while}适配器第一次看到空行时就会停止迭代，因此这段代码只会打印出两行：
\begin{minted}{text}
    To: jimb
    From: superego <editor@oreilly.com>
\end{minted}

\subsection{\texttt{skip}和\texttt{skip\_while}}
\texttt{Iterator} trait的\texttt{skip}和\texttt{skip\_while}方法是\texttt{take}和\texttt{take\_while}的补充：它们丢弃迭代起始的一定数量的item，或者直到一个闭包找到一个可接受的item时，按原样传递这个和剩余的item。它们的签名如下：
\begin{minted}{Rust}
    fn skip(self, n: usize) -> impl Iterator<Item=Self::Item>
        where Self: Sized;

    fn skip_while<P>(self, predicate: P) -> impl Iterator<Item=Self::Item>
        where Self: Sized, P: FnMut(&Self::Item) -> bool;
\end{minted}

\texttt{skip}适配器的一个常见用法是在迭代命令行参数时跳过命令的名字。在\hyperref[ch02]{第2章}中，我们的最大公约数计算器就用了下面的代码来迭代它的命令行参数：
\begin{minted}{Rust}
    for arg in std::env::args().skip(1) {
        ...
    }
\end{minted}

\texttt{std::env::args}函数返回一个迭代器，以\texttt{String}类型产生程序的参数，其中第一个item就是程序自身的名字。我们并不想在这个循环中处理它。对这个迭代器调用\texttt{skip(1)}返回一个新的迭代器，新的迭代器会丢弃程序名，然后产生剩余的参数。

\texttt{skip\_while}适配器使用闭包来决定丢弃序列开头的多少item。你可以像这样迭代上一节的消息的主体行：
\begin{minted}{Rust}
    for body in message.lines()
        .skip_while(|l| !l.is_empty())
        .skip(1)
        println!("{}", body);
\end{minted}

这里使用了\texttt{skip\_while}来跳过非空的行，但这个迭代器会产生那个空行——也就是使闭包返回\texttt{false}的那个item。因此我们使用了\texttt{skip}方法来丢弃那个空行，这样最后的迭代器的第一个item就是消息主体的第一行。结合上一节中的\texttt{message}，这段代码会打印出：
\begin{minted}{text}
    Did you get any writing done today?
    When will you stop wasting time plotting fractals?
\end{minted}

\subsection{\texttt{peekable}}
peekable迭代器让你可以窥视下一个将被产生的item，而不实际消耗它。你可以通过调用\texttt{Iterator} trait的\texttt{peekable}方法把一个迭代器转换成一个peekable迭代器：
\begin{minted}{Rust}
    fn peekable(self) -> std::iter::Peekable<Self>
        where Self: Sized;
\end{minted}
这里，\texttt{Peekable<Self>}是一个实现了\texttt{Iterator<Item=Self::Item>}的\texttt{struct}，其中\texttt{Self}是底层迭代器的类型。

\texttt{Peekable}迭代器有一个额外的\texttt{peek}方法返回一个\texttt{Option<\&Item>}：如果底层迭代器已经迭代完就返回\texttt{None}，否则返回\texttt{Some(r)}，其中\texttt{r}是下一个item的共享引用。（注意如果底层迭代器的item的类型已经是一个引用，那么最后返回的将是一个引用的引用。）

调用\texttt{peek}会尝试获取底层迭代器的下一个item，如果确实还有item，就缓存它直到下一次调用\texttt{next}。\texttt{Peekable}的其他\texttt{Iterator}的方法都知道这个缓存：例如，一个peekable迭代器\texttt{iter}的调用\texttt{iter.last()}知道在耗尽了底层的迭代器之后检查缓存。

当你必须要遍历之后才知道到底要消耗多少item时，peekable迭代器就很重要了。例如，如果你正在一个字符流解析数字，只有当你看到了数字之后的第一个非数字字符时你才能知道数字在哪里结束：
\begin{minted}{Rust}
    use std::iter::Peekable;

    fn parse_number<I>(tokens: &mut Peekable<I>) -> u32
        where I: Iterator<Item=char>
    {
        let mut n = 0;
        loop {
            match tokens.peek() {
                Some(r) if r.is_digit(10) => {
                    n = n * 10 + r.to_digit(10).unwrap();
                }
                _ => return n;
            }
            tokens.next();
        }
    }

    let mut chars = "226153980,1766319049".chars().peekable();
    assert_eq!(parse_number(&mut chars), 226153980);
    // `parse_number`不会消耗逗号！因此下面不会出错。
    assert_eq!(chars.next(), Some(','));
    assert_eq!(parse_number(&mut chars), 1766319049);
    assert_eq!(chars.next(), None);
\end{minted}


\texttt{parse\_number}函数使用\texttt{peek}方法来检查下一个字符，并且只有当它是数字时才消耗它。如果它不是数字或者迭代器被耗尽（也就是，如果\texttt{peek}返回\texttt{None}），我们将会返回已经解析的数字，将下一个字符留在迭代器里，之后再消耗。

\subsection{\texttt{fuse}}\label{fuse}
一旦一个\texttt{Iterator}返回\texttt{None}，trait并没有指定如果你继续调用\texttt{next}方法时它的行为。大多数迭代器都是再次返回\texttt{None}，但并不是所有。如果你的代码依赖这种行为，那你有时可能会遇到奇怪的行为。

\texttt{fuse}适配器接受任何迭代器，并产生一个保证第一次返回\texttt{None}之后一直返回\texttt{None}的迭代器：
\begin{minted}{Rust}
    struct Flaky(bool);

    impl Iterator for Flaky {
        type Item = &'static str;
        fn next(&mut self) -> Option<Self::Item> {
            if self.0 {
                self.0 = false;
                Some("totally the last item")
            } else {
                self.0 = true;  // D'oh!
                None
            }
        }
    }

    let mut flaky = Flaky(true);
    assert_eq!(flaky.next(), Some("totally the last item"));
    assert_eq!(flaky.next(), None);
    assert_eq!(flaky.next(), Some("totally the last item"));

    let mut not_flaky = Flaky(true).fuse();
    assert_eq!(not_flaky.next(), Some("totally the last item"));
    assert_eq!(not_flaky.next(), None);
    assert_eq!(not_flaky.next(), None);
\end{minted}

\texttt{fuse}适配器最有用的场景可能是需要使用不确定来源的迭代器的泛型代码。与其希望每一个要处理的迭代器都是良定义的，不如使用\texttt{fuse}来确保这种行为。

\subsection{可逆迭代器和\texttt{rev}}
一些迭代器可以从序列的任意一端产生item。你可以通过使用\texttt{rev}适配器来反转这样的迭代器。例如，一个vector的迭代器可以简单的从尾部到头部产生item。这样的迭代器可以实现\texttt{std::iter::DoubleEndedIterator} trait，它是\texttt{Iterator}的扩展：
\begin{minted}{Rust}
    trait DoubleEndedIterator: Iterator {
        fn next_back(&mut self) -> Option<Self::Item>;
    }
\end{minted}

你可以将这样的双端迭代器看做有两个标记分别指向正向和反向迭代的位置。每次从其中一个产生item，都会让它向另一个的方向移动；当它们交汇的时候，迭代就结束了：
\begin{minted}{Rust}
    let bee_parts = ["head", "thorax", "abdomen"];

    let mut iter = bee_parts.iter();
    assert_eq!(iter.next(),      Some(&"head"));
    assert_eq!(iter.next_back(), Some(&"abdomen"));
    assert_eq!(iter.next(),      Some(&"thorax"));

    assert_eq!(iter.next_back(), None);
    assert_eq!(iter.next_back(), None);
\end{minted}

切片的迭代器可以很容易的实现这种行为：它利用两个指针分别指向还未产生的元素范围的起点和终点；\texttt{next}和\texttt{next\_back}简单地从其中一个产生一个item。有序集合的迭代器例如\texttt{BTreeSet}和\texttt{BTreeMap}也是双端迭代器：它们的\texttt{next\_back}方法以最大元素或条目优先的顺序返回item。一般来说，标准库在可行时都会提供双端迭代器。

但并不是所有的迭代器都可以简单地做到这一点：一个产生其他线程发给通道的\texttt{Receiver}的值的迭代器没有办法预测最后一个到达的值会是什么。一般来说，你应该检查标准库的文档来看看哪些迭代器实现了\texttt{DoubleEndedIterator}，哪些没有。

如果一个迭代器是双端的，你可以使用\texttt{rev}适配器来反转它：
\begin{minted}{Rust}
    fn rev(self) -> impl Iterator<Item=Self>
        where Self: Sized + DoubleEndedIterator;
\end{minted}

返回的迭代器也是一个双端迭代器：它的\texttt{next}和\texttt{next\_back}方法被简单地交换了：
\begin{minted}{Rust}
    let meals = ["breakfast", "lunch", "dinner"];

    let mut iter = meals.iter().rev();
    assert_eq!(iter.next(), Some(&"dinner"));
    assert_eq!(iter.next(), Some(&"lunch"));
    assert_eq!(iter.next(), Some(&"breakfast"));
    assert_eq!(iter.next(), None);
\end{minted}

大多数迭代器适配器如果被用于可逆迭代器，会返回另一个可逆迭代器。例如，\texttt{map}和\texttt{filter}会保留可逆性。

\subsection{\texttt{inspect}}
\texttt{inspect}适配器在调试迭代器适配器的流水线时很有用，但通常不用在生产代码中。它简单地对每一个item的共享引用应用一个闭包然后传递它们。闭包不能影响到item，但可以做一些类似于打印或进行断言的操作。

这个例子展示了一个将字符串转换为大写会改变长度的例子：
\begin{minted}{Rust}
    let upper_case: String = "große".chars()
        .inspect(|c| println!("before: {:?}", c))
        .flat_map(|c| c.to_uppercase())
        .inspect(|c| println!(" after:     {:?}", c))
        .collect();
    assert_eq!(upper_case, "GROSSE");
\end{minted}

小写德语字母“ß”的大写形式是“SS”，这就是为什么\texttt{char::to\_uppercase}会返回一个产生字符的迭代器，而不是单个字符。上面的代码中使用\texttt{flat\_map}来把所有\texttt{to\_uppercase}序列连接成单个\texttt{String}，它会打印出下列内容：
\begin{minted}{text}
    before: 'g'
     after:     'G'
    before: 'r'
     after:     'R'
    before: 'o'
     after:     'O'
    before: 'ß'
     after:     'S'
     after:     'S'
    before: 'e'
     after:     'E'
\end{minted}

\subsection{\texttt{chain}}
\texttt{chain}迭代器适配器将一个迭代器附加到另一个之后。更确切地说，\texttt{i1.chain(i2)}返回的迭代器会首先产生\texttt{i1}的item，当\texttt{i1}耗尽后，再继续产生\texttt{i2}的item。

\texttt{chain}适配器的签名如下：
\begin{minted}{Rust}
    fn chain<U>(self, other: U) -> impl Iterator<Item=Self::Item>
        where Self: Sized, U: IntoIterator<Item=Self::Item>;
\end{minted}

换句话说，你可以将任何产生相同类型item的迭代器连接起来。
例如：
\begin{minted}{Rust}
    let v: Vec<i32> = (1..4).chain(vec![20, 30, 40]).collect();
    assert_eq!(v, [1, 2, 3, 20, 30, 40]);
\end{minted}

如果两个底层迭代器都是可逆的，那么\texttt{chain}迭代器也是可逆的：
\begin{minted}{Rust}
    let v: Vec<i32> = (1..4).chain(vec![20, 30, 40]).rev().collect();
    assert_eq!(v, [40, 30, 20, 3, 2, 1]);
\end{minted}

一个\texttt{chain}迭代器会追踪是否两个底层迭代器返回过\texttt{None}，并正确地调用\texttt{next}或者\texttt{next\_back}。

\subsection{\texttt{enumerate}}\label{enumerate}
\texttt{Iterator} trait的\texttt{enumerate}适配器把一个索引附加到序列中，它以一个产生\texttt{A, B, C, ...}的迭代器为参数，返回一个产生\texttt{(0, A), (1, B), (2, C), ...}的迭代器。第一眼可能会觉得它用处不大，但实际上它非常常用。

消费者可以使用索引来区分不同的item并建立起处理每个item的上下文。例如，\hyperref[ch02]{第2章}中的曼德勃罗集绘制器将图像分割成了8个水平的条带，并把每个条带分到不同的线程中进行处理。那段代码使用了\texttt{enumerate}来告诉每个线程它的条带是图像中的哪一部分。

它以一个矩形像素的缓冲区开始：
\begin{minted}{Rust}
    let mut pixels = vec![0; columns * rows];
\end{minted}
然后，它使用了\texttt{chunks\_mut}把图像分割成水平的条带，每个线程一个条带：
\begin{minted}{Rust}
    let threads = 8;
    let band_rows = rows / threads + 1;
    ...
    let bands: Vec<&mut [u8]> = pixels.chunks_mut(band_rows * columns).collect();
\end{minted}

然后它迭代条带，为每个条带开启一个新线程：
\begin{minted}{Rust}
    for (i, band) in bands.into_iter().enumerate() {
        let top = band_rows * i;
        // 启动一个线程渲染`top..top + band_rows"范围内的行
        ...
    }
\end{minted}

每一次迭代会得到一个\texttt{(i, band)}，其中\texttt{band}是这个线程应该绘制的像素缓冲区的\texttt{\&mut [u8]}切片，\texttt{i}是条带在整个图片中的索引，由\texttt{enumerate}适配器产生。给定图像的长宽和条带的大小，一个线程就获取了足够的信息来判断它要处理的是图像的哪一部分，并且因此能正确绘制\texttt{band}。

你可以将\texttt{enumerate}产生的\texttt{(index, item)}类比迭代\texttt{HashMap}或其他关联集合时得到的\texttt{(key, value)}对。如果你在迭代一个切片或者vector，那么\texttt{index}就是\texttt{item}出现的“key”。

\subsection{\texttt{zip}}
\texttt{zip}适配器将两个迭代器组合成单个迭代器，它一次产生一个pair，pair里分别是两个迭代器产生的item，就像是一条拉链一样把两边汇聚成单条缝隙。当两个底层迭代器中有任何一个结束时，zip迭代器也会结束。

例如，你可以通过把无限范围\texttt{0..}和另一迭代器zip在一起来达到\texttt{enumerate}适配的效果：
\begin{minted}{Rust}
    let v: Vec<_> = (0..).zip("ABCD".chars()).collect();
    assert_eq!(v, vec![(0, 'A'), (1, 'B'), (2, 'C'), (3, 'D')]);
\end{minted}

从这个意义上讲，你可以将\texttt{zip}看做\texttt{enumerate}的泛化版：\texttt{enumerate}把索引附加序列中，\texttt{zip}把任意另一个迭代器的item附加到序列中。我们之前建议过\texttt{enumerate}可以帮助提供处理item的上下文；\texttt{zip}是一种更灵活的实现同样功能的方式。

\texttt{zip}的参数不需要是一个和调用者自己同类型的迭代器；它可以是任意的可迭代对象：
\begin{minted}{Rust}
    use std::iter::repeat;

    let endings = vec!["once", "twice", "chicken soup with rice"];
    let rhyme: Vec<_> = repeat("going")
        .zip(endings)
        .collect();
    assert_eq!(rhyme, vec![("going", "once"),
                           ("going", "twice"),
                           ("going", "chicken soup with rice")]);
\end{minted}

\subsection{\texttt{by\_ref}}
在本节中，我们已经见过很多次把适配器附加到迭代器上。但一旦这么做了之后，还可以把适配器去除掉吗？通常是不行的：适配器会获取底层迭代器的所有权，而且不提供方法返回底层迭代器。

迭代器的\texttt{by\_ref}方法借用一个迭代器的可变引用，然后你可以对这个引用应用适配器。当你消耗完这些适配器的item之后，你会drop它们，然后借用结束，你可以重新访问原本的迭代器。

例如，本章前面我们展示过怎么使用\texttt{take\_while}和\texttt{skip\_while}来处理邮件消息的消息头或者主体。但如果你想用同一个底层迭代器同时处理两者呢？使用\texttt{by\_ref}，我们可以使用\texttt{take\_while}来处理消息头，然后等它结束之后重新获得底层迭代器的访问权，而\texttt{take\_while}结束之后底层迭代器恰好留在消息主体的位置上：
\begin{minted}{Rust}
    let message = "To: jimb\r\n\
                  From: id\r\n\
                  \r\n\
                  Oooooh, donuts!!\r\n";

    let mut lines = message.lines();

    println!("Headers:");
    for header in liens.by_ref().take_while(|l| !l.is_empty()) {
        println!("{}", header);
    }

    println!("\nBody:");
    for body in lines {
        println!("{}", body);
    }
\end{minted}
\texttt{line.by\_ref()}调用借用了迭代器的可变引用，然后\texttt{take\_while}获取的是这个可变引用的所有权。当第一个\texttt{for}循环结束时，这个引用就离开了作用域，这意味着借用结束了，因此你可以在第二个\texttt{for}循环中再次使用\texttt{lines}。这会打印出下面的内容：
\begin{minted}{text}
    Headers:
    To: jimb
    From: id

    Body:
    Oooooh, donuts!
\end{minted}

\texttt{by\_ref}适配器的定义很简单，它返回一个迭代器的可变引用。然后，标准库包含这个奇怪的实现：
\begin{minted}{Rust}
    impl<'a, I: Iterator + ?Sized> Iterator for &'a mut I {
        type Item = I::Item;
        fn next(&mut self) -> Option<I::Item> {
            (**self).next()
        }
        fn size_hint(&self) -> (usize, Option<usize>) {
            (**self).size_hint()
        }
    }
\end{minted}

换句话说，如果\texttt{I}是迭代器，那么\texttt{\&mut I}也是一个迭代器，它的\texttt{next}和\texttt{size\_hint}方法指向它引用的对象的相应方法。当你在一个迭代器的可变引用上调用适配器时，适配器会获取\emph{引用}的所有权，而不是迭代器本身的所有权。它只是一个当适配器离开作用域时就会结束的借用。

\subsection{\texttt{cloned}和\texttt{copied}}
\texttt{cloned}适配器获取一个产生引用的迭代器，然后返回一个产生这些引用的拷贝操作返回的值的迭代器。就类似于\texttt{iter.map(|item| item.clone())}。自然地，被引用的类型必须实现\texttt{Clone}。例如：
\begin{minted}{Rust}
    let a = ['1', '2', '3', '='];
    assert_eq!(a.iter().next(),          Some(&'a'));
    assert_eq!(a.iter().cloned().next(), Some('1'));
\end{minted}

\texttt{copied}适配器也是相同的思路，但更加严格：被引用的类型必须实现\texttt{Copy}。\\
\texttt{iter.copied()}调用类似于\texttt{iter.map(|r| *r)}。因为每个实现了\texttt{Copy}的类型都实现了\texttt{Clone}，所以\texttt{cloned}通常更一般化，但根据item的类型不同，\texttt{clone}调用可以做任意次的分配和拷贝操作。如果你假设你的item的类型足够简单所以永远不会发生这种情况，那么最好的方法还是使用\texttt{copied}来让类型检查器检查你的假设。

\subsection{\texttt{cycle}}
\texttt{cycle}适配器返回一个无限重复底层迭代器产生的序列的迭代器。底层迭代器必须实现了\texttt{std::clone::Clone}，这样\texttt{cycle}才可以保存它的初始状态，然后在每一次循环开始时重用它。

例如：
\begin{minted}{Rust}
    let dirs = ["North", "East", "South", "West"];
    let mut spin = dirs.iter().cycle();
    assert_eq!(spin.next(), Some(&"North"));
    assert_eq!(spin.next(), Some(&"East"));
    assert_eq!(spin.next(), Some(&"South"));
    assert_eq!(spin.next(), Some(&"West"));
    assert_eq!(spin.next(), Some(&"North"));
    assert_eq!(spin.next(), Some(&"East"));
\end{minted}

或者，完全没有任何开销地使用它：
\begin{minted}{Rust}
    use std::iter::{once, repeat};

    let fizzes = repeat("").take(2).chain(once("fize")).cycle();
    let buzzes = repeat("").take(4).chain(once("buzz")).cycle();
    let fizzes_buzzes = fizzes.zip(buzzes);

    let fizz_buzz = (1..100).zip(fizzes_buzzes)
        .map(|tuple|
             match tuple {
                 (i, ("", "")) => i.to_string(),
                 (_, (fizz, buzz)) => format!("{}{}", fizz, buzz)
             });
    
    for line in fizz_buzz {
        println!("{}", line);
    }
\end{minted}

这样就完成了一个小孩子的单词游戏，现在有时也会被用作程序员的面试题目。在这个游戏中，玩家要轮流计数，把任何能被3整除的数替换成单词\texttt{fizz}，任何能被5整除的数替换成\texttt{fizzbuzz}。能被3和5同时整除的数替换为\texttt{fizzbuzz}。

\section{消耗迭代器}

到目前为止，我们已经介绍了创建迭代器和用适配器将它们包装成新的迭代器；接下来我们将展示如何消耗它们来结束这个过程。

当然，你可以使用\texttt{for}循环来消耗一个迭代器，或者显式地调用\texttt{next}，但有很多常见的任务没必要一次又一次地写出来。\texttt{Iterator} trait提供了许多的方法来处理很多常用的情况。

\subsection{简单的累计：\texttt{count, sum, product}}
\texttt{count}方法不断从一个迭代器获取item直到它返回\texttt{None}，然后告诉你它到底获得了多少个item。这里有一个简短的程序来统计标准输入的行数：
\begin{minted}{Rust}
    use std::io::predule::*;

    fn main() {
        let stdin = std::io::stdin();
        println!("{}", stdin.lock().lines().count());
    }
\end{minted}

\texttt{sum}和\texttt{product}方法计算迭代器的item的和或者积，item必须是整数或者浮点数：
\begin{minted}{Rust}
    fn triangle(n: u64) -> u64 {
        (1..=n).sum()
    }
    assert_eq!(triangle(20), 210);

    fn factorial(n: u64) -> u64 {
        (1..=n).product()
    }
    assert_eq!(factorial(20), 2432902008176640000);
\end{minted}

（你可以通过实现\texttt{std::iter::Sum}和\texttt{std::iter::Product} trait来扩展\texttt{sum}和\texttt{product}以支持其他类型，但本书中不会介绍。）

\subsection{\texttt{max, min}}
\texttt{Iterator}的\texttt{min}和\texttt{max}方法分别返回迭代器产生的item中最小的和最大的。item的类型必须实现了\texttt{std::cmp::Ord}，这样才可以互相比较。例如：
\begin{minted}{Rust}
    assert_eq!([-2, 0, 1, 0, -2, -5].iter().max(), Some(&1));
    assert_eq!([-2, 0, 1, 0, -2 ,-5].iter().min(), Some(&-5));
\end{minted}

这些方法返回\texttt{Option<Self::Item>}，这样如果迭代器没产生值的时候可以返回\texttt{None}。

正如\nameref{equal}中解释的一样，Rust的浮点数类型\texttt{f32}和\texttt{f64}只实现了\\
\texttt{std::cmp::PartialOrd}，没有实现\texttt{std::cmp::Ord}，因此你不能使用\texttt{min}和\texttt{max}方法来计算浮点数序列中的最小值或最大值。这不是Rust设计中的优势，但它是故意的：因为不清楚这样的函数如果遇到了IEEE NaN值时该怎么处理。简单地忽略它们可能会导致代码中更严重的问题。

如果你知道如何处理NaN值，你可以使用\texttt{max\_by}和\texttt{min\_by}迭代器方法作为代替，它允许你提供自己的比较函数。

\subsection{\texttt{max\_by, min\_by}}\label{MaxBy}
\texttt{max\_by}和\texttt{min\_by}方法分别返回迭代器产生的最大值和最小值，通过一个你提供的比较函数来判断大小：
\begin{minted}{Rust}
    use std::cmp::Ordering;

    // 比较两个f64值，如果有NaN就panic
    fn cmp(lhs: &f64, rhs: &f64) -> Ordering {
        lhs.partial_cmp(rhs).unwrap()
    }
    
    let numbers = [1.0, 4.0, 2.0];
    assert_eq!(numbers.iter().copied().max_by(cmp), Some(4.0));
    assert_eq!(numbers.iter().copied().min_by(cmp), Some(1.0));

    let numbers = [1.0, 4.0, std::f64::NAN, 2.0];
    assert_eq!(numbers.iter().copied().max_by(cmp), Some(4.0)); // panic
\end{minted}

\texttt{max\_by}和\texttt{min\_by}方法以引用的方式把item传递给比较函数，这样不管迭代器产生什么类型的值它们都可以高效工作。因此这里\texttt{cmp}要以引用获取参数，即使我们已经使用\texttt{copied}获取过一个产生\texttt{f64} item的迭代器。

\subsection{\texttt{max\_by\_key, min\_by\_key}}
\texttt{Iterator}的\texttt{max\_by\_key}和\texttt{min\_by\_key}方法通过比较对item调用闭包返回的值来分别返回最大值和最小值。闭包可以选择item的某些字段或者对item进行计算。因为你通常对最大和最小值相关联的数据感兴趣，而不是对极值本身感兴趣，因此这些方法通常比\texttt{max}和\texttt{min}更有用。它们的签名如下：
\begin{minted}{Rust}
    fn min_by_key<B: Ord, F>(self, f: F) -> Option<Self::Item>
        where Self: Sized, F: FnMut(&Self::Item) -> B;

    fn max_by_key<B: Ord, F>(self, f: F) -> Option<Self::Item>
        where Self: Sized, F: FnMut(&Self::Item) -> B;
\end{minted}

这两个方法接受一个闭包\texttt{f}作为参数，\texttt{f}需要接受一个item并返回一个有序的类型\texttt{B}。然后这两个方法对每个item都调用\texttt{f}，根据返回的\texttt{B}类型的值来比较大小，最后分别返回最大和最小的item，或者如果没有item产生时返回\texttt{None}。

例如，如果你需要扫描一个城市的哈希表来查找人口最多和最少的城市，你可以写：
\begin{minted}{Rust}
    use std::collections::HashMap;

    let mut populations = HashMap::new();
    populations.insert("Portland",  583_776);
    populations.insert("Fossil",        449);
    populations.insert("Greenhorn",       2);
    populations.insert("Boring",      7_762);
    populations.insert("The Dalles", 15_340);

    assert_eq!(populations.iter().max_by_key(|&(_name, pop)| pop),
               Some((&"Portland", &583_776)));
    assert_eq!(populations.iter().min_by_key(|&(_name, pop)| pop),
               Some((&"Greenhorn", &2)));
\end{minted}

闭包\texttt{|\&(\_name, pop)| pop}会应用到迭代器产生的每个item，然后返回用于比较的值——在这个例子中，就是城市的人口。最后返回的值是整个item，而不仅仅是闭包返回的值。（当然，如果你经常进行这样的查询，你可能会需要一种更高效的存储方式来查找，而不是在这样的表上进行线性查找。）

\subsection{比较item序列}
你可以使用\texttt{<}和\texttt{==}运算符来比较字符串、vector、切片，假设它们的元素可以被比较。尽管迭代器不支持Rust的比较运算符，但它们确实提供了方法例如\texttt{eq}和\texttt{lt}来做相同的工作，这些方法每次从两个迭代器各取一个item进行比较，直到可以比较出结果。例如：
\begin{minted}{Rust}
    let packed =  "Helen of Troy";
    let spaced =  "Helen   of    Troy";
    let obscure = "Helen of Sandusky";  // 好人，只是没名气

    assert!(packed != spaced);
    assert!(packed.split_whitespace().eq(spaced.split_whitespace()));

    // 比较为真，因为' ' < 'o'
    assert!(spaced < obscure);

    // 比较为真，因为'Troy' > 'Sandusky'
    assert!(spaced.split_whitespace().gt(obscure.split_whitespace()));
\end{minted}

\texttt{split\_whitespace}的调用返回一个迭代字符串中空格分隔的单词的迭代器。对这些迭代器使用\texttt{eq}和\texttt{gt}方法会进行逐单词的比较，而不是逐字符比较。这些比较都是可行的，因为\texttt{\&str}实现了\texttt{PartialOrd}和\texttt{PartialEq}。

迭代器提供\texttt{eq}和\texttt{ne}方法进行相等性比较，以及\texttt{lt, le, gt, ge}方法用于顺序性比较。\texttt{cmp}和\texttt{partial\_cmp}方法的行为类似于\texttt{Ord}和\texttt{PartialOrd} trait的相应方法。

\subsection{\texttt{any}和\texttt{all}}
\texttt{any}和\texttt{all}方法对迭代器产生的每一个item都应用一个闭包，分别当任意item使闭包返回\texttt{true}和所有item都使闭包返回\texttt{true}时返回\texttt{true}：
\begin{minted}{Rust}
    let id = "Iterator";

    assert!( id.chars().any(char::is_uppercase));
    assert!(!id.chars().all(char::is_uppercase));
\end{minted}

只有当需要的时候这两个方法才会继续消耗item。例如，如果已经有一个item让闭包返回\texttt{true}，那么\texttt{any}会立刻返回\texttt{true}，不会再继续消耗剩余的item。

\subsection{\texttt{position, rposition, ExactSizeIterator}}
\texttt{position}方法应用到迭代器的每一个item上，返回第一个使闭包返回\texttt{true}的item的索引。更确切地说，它返回一个索引的\texttt{Option}：如果没有item使闭包返回\texttt{true}，\texttt{position}会返回\texttt{None}。只要闭包有一次返回\texttt{true}它就会立刻停止。例如：
\begin{minted}{Rust}
    let text = "Xerxes";
    assert_eq!(text.chars().position(|c| c == 'e'), Some(1));
    assert_eq!(text.chars().position(|c| c == 'z'), None);
\end{minted}

\texttt{rposition}方法功能相同，不过它是从最后一个元素往前开始搜索。例如：
\begin{minted}{Rust}
    let bytes = b"Xerxes";
    assert_eq!(bytes.iter().rposition(|&c| c == b'e'), Some(4));
    assert_eq!(bytes.iter().rposition(|&c| c == b'X'), Some(0));
\end{minted}
\texttt{rposition}方法要求一个可逆迭代器这样它才可以从最后往前遍历。它还要求一个exact-size迭代器这样它才可以返回一个和\texttt{position}一样的索引，即从前往后数情况下的索引。exact-size迭代器是一个实现了\texttt{std::iter::ExactSizeIterator} trait的迭代器：
\begin{minted}{Rust}
    trait ExactSizeIterator: Iterator {
        fn len(&self) -> usize { ... }
        fn is_empty(&self) -> bool { ... }
    }
\end{minted}

\texttt{len}方法返回剩余item的数量，当迭代结束时\texttt{is\_empty}方法返回\texttt{true}。

当然，不是每一个迭代器都知道它还会产生多少个item。例如，之前使用的\texttt{str::chars}迭代器就做不到（因为UTF-8是可变宽度的编码），因此你不能对字符串使用\texttt{rposition}。但一个迭代字节数组的迭代器当然知道数组的长度，因此它可以实现\texttt{ExactSizeIterator}。

\subsection{\texttt{fold}和\texttt{rfold}}
在进行某种需要累计所有item的计算时\texttt{fold}方法是非常通用的工具。给定一个初始值（我们称之为\emph{累加器(accumulator)}）和一个闭包，\texttt{fold}会重复对当前的累加器和下一个item应用这个闭包。闭包返回的值被用作新的累加器，然后和下一个item一起传递给闭包。最终累加器的值就是\texttt{fold}自身的返回值。如果序列为空，\texttt{fold}直接返回初始的累加器。

很多其他消耗迭代器的方法都可以用\texttt{fold}来实现：
\begin{minted}{Rust}
    let a = [5, 6, 7, 8, 9, 10];

    assert_eq!(a.iter().fold(0, |n, _| n+1), 6);        // count
    assert_eq!(a.iter().fold(0, |n, i| n+i), 45);       // sum
    assert_eq!(a.iter().fold(1, |n, i| n*i), 151200);   // product

    // max
    assert_eq!(a.iter().cloned().fold(i32::min_value(), std::cmp::max), 10);
\end{minted}

\texttt{fold}方法的签名如下：
\begin{minted}{Rust}
    fn fold<A, F>(self, init: A, f: F) -> A
        where Self: Sized, F: FnMut(A, Self::Item) -> A;
\end{minted}

其中，\texttt{A}是累加器的类型。\texttt{init}参数就是一个\texttt{A}类型的值，\texttt{A}也是闭包的第一个参数和返回值的类型，也是\texttt{fold}本身的返回值的类型。

注意累加器值被移动进和移出闭包，因此你可以用非\texttt{Copy}的累加器类型调用\texttt{fold}：
\begin{minted}{Rust}
    let a = ["Pack", "my", "box", "with",
             "five", "dozen", "liquor", "jugs"];
    
    // See also：切片的`join`方法，最后不会有多余的空格。
    let pangram = a.iter().fold(String::new(), |s, w| s + w + " ");
    assert_eq!(pangram, "Pack my box with five dozen liquor jugs");
\end{minted}

\texttt{rfold}方法和\texttt{fold}方法相同，除了它需要双端迭代器，并且从最后开始往前处理item：
\begin{minted}{Rust}
    let weird_pangram = a.iter().rfold(String::new(), |s, w| s + w + " ");
    assert_eq!(weird_pangram, "jugs liquor dozen five with box my Pack ");
\end{minted}

\subsection{\texttt{try\_fold}和\texttt{try\_rfold}}
\texttt{try\_fold}方法和\texttt{fold}基本一样，除了它的迭代过程可以提前退出，不需要消耗迭代器里的所有值。传递给\texttt{try\_fold}的闭包需要返回一个\texttt{Result}：如果它是\texttt{Err(e)}，\texttt{try\_fold}会立刻返回\texttt{Err(e)}作为返回值。否则，它会继续处理成功的值。闭包也可以返回一个\texttt{Option}：返回\texttt{None}会提前退出，最后的返回值是个\texttt{Option}。

这里有一个求来自标准输入的数字之和的程序：
\begin{minted}{Rust}
    use std::error::Error;
    use std::io::predule::*;
    use std::str::FromStr;

    fn main() -> Result<(), Box<dyn Error>> {
        let stdin = std::io::stdin();
        let sum = stdin.lock()
            .lines()
            .try_fold(0, |sum, line| -> Result<u64, Box<dyn Error>> {
                Ok(sum + u64::from_str(&line?.trim())?)
            })?;
        println!("{}", sum);
        Ok(())
    }
\end{minted}

输入流的\texttt{lines}迭代器产生\texttt{Result<String, std::io::Error>}类型的item，把\texttt{String}解析为整数也可能会失败。这里使用\texttt{try\_fold}需要闭包返回\texttt{Result<u64, ...>}，所以我们可以使用\texttt{?}运算符来把闭包里的错误传播到\texttt{main}函数中。

因为\texttt{try\_fold}如此灵活，它常被用于实现\texttt{Iterator}的很多其他消耗方法。例如，这里有一个\texttt{all}的实现：
\begin{minted}{Rust}
    fn all<P>(&mut self, mut predicate: P) -> bool
        where P: FnMut(Self::Item) -> bool,
              Self: Sized
    {
        self.try_fold((), |_, item| {
            if predicate(item) { Some(()) } else { None }
        }).is_some()
    }
\end{minted}

注意这个实现不能使用普通的\texttt{fold}：\texttt{all}保证只要有一个item使\texttt{predicate}返回false就会停止消耗item，但\texttt{fold}总是消耗整个迭代器。

如果你正在实现自己的迭代器类型，那么思考一下你的迭代器是否能比\texttt{Iterator} trait的默认实现更高效地实现\texttt{try\_fold}方法是值得的。如果你可以加速\texttt{try\_fold}，所有其他基于它的方法都会获益。

\texttt{try\_rfold}方法，就如它的名字所示，和\texttt{try\_fold}一样，除了它从最后开始往前处理item，并因此需要一个双端迭代器。

\subsection{\texttt{nth, nth\_back}}
\texttt{nth}方法接受一个索引\texttt{n}，跳过迭代器中接下来\texttt{n}个item，然后返回下一个item，或者如果迭代器已经在这个过程中到达终点就返回\texttt{None}。调用\texttt{.nth(0)}等价于调用\texttt{.next()}。

它不会像很多适配器一样获取迭代器的所有权，所以你可以调用它很多次：
\begin{minted}{Rust}
    let mut squares = (0..10).map(|i| i*i);

    assert_eq!(squares.nth(4), Some(16));
    assert_eq!(squares.nth(0), Some(25));
    assert_eq!(squares.nth(6), None);
\end{minted}

它的签名如下：
\begin{minted}{Rust}
    fn nth(&mut self, n: usize) -> Option<Self::Item>
        where Self: Sized;
\end{minted}

\texttt{nth\_back}方法类似，除了它是从双端迭代器的尾部往前移动。调用\texttt{.nth\_back(0)}等价于调用\texttt{.next\_back()}：它返回最后一个item，或者如果迭代器已经为空时返回\texttt{None}。

\subsection{\texttt{last}}
\texttt{last}方法返回迭代器产生的最后一个item，或者如果迭代器为空时返回\texttt{None}。它的签名如下：
\begin{minted}{Rust}
    fn last(self) -> Option<Self::Item>;
\end{minted}

例如：
\begin{minted}{Rust}
    let squares = (0..10).map(|i| i*i);
    assert_eq!(squares.last(), Some(81));
\end{minted}

它会消耗迭代器的所有item，即使迭代器可逆。如果你有一个可逆迭代器并且不想让它消耗所有item，那你应该调用\texttt{iter.next\_back()}。

\subsection{\texttt{find, rfind, find\_map}}
\texttt{find}方法从迭代器查找item，返回第一个使给定闭包返回\texttt{true}的item，或者如果没有任何item满足条件就返回\texttt{None}。它的签名是：
\begin{minted}{Rust}
    fn find<P>(&mut self, predicate: P) -> Option<Self::Item>
        where Self: Sized,
              P: FnMut(&Self::Item) -> bool;
\end{minted}

\texttt{rfind}方法类似，不过它需要双端迭代器并且从最后往前搜索，返回\emph{最后一个}使闭包返回\texttt{true}的item。

例如，使用\nameref{MaxBy}中的城市和人口的表，你可以写：
\begin{minted}{Rust}
    assert_eq!(populations.iter().find(|&(_name, &pop)| pop > 1_000_000), None);
    assert_eq!(populations.iter().find(|&(_name, &pop)| pop > 500_000), Some((&"Portland", &583_776)));
\end{minted}

表中没有人口超过一百万的城市，但有超过50万的城市。

有时你的闭包并不是一个简单的对item进行布尔判断的判别式：它可能会更加复杂，并且返回一个它自己产生的有趣的值。在这种情况下，\texttt{find\_map}正是你需要的。它的签名是：
\begin{minted}{Rust}
    fn find_map<B, F>(&mut self, f: F) -> Option<B> where
        F: FnMut(Self::Item) -> Option<B>;
\end{minted}

这类似于\texttt{find}，区别在于它接受的闭包不是返回\texttt{bool}，而是返回一个\texttt{Option}。\texttt{find\_map}返回第一个是\texttt{Some}的\texttt{Option}。

例如，如果我们有一个每个城市的公园的数据库，我们可能想看看其中是否有火山，并且如果有的话返回公园的名字：
\begin{minted}{Rust}
    let big_city_with_volcano_park = populations.iter()
        .find_map(|(&city, _)| {
            if let Some(park) = find_volcano_park(city, &parks) {
                // find_map返回这个值，
                // 因此我们的调用者会知道我们找到了 *哪个* 公园
                return Some((city, park.name));
            }

            // 继续搜索
            None
        });

    assert_eq!(big_city_with_volcano_park,
               Some(("Portland", "Mt. Tabor Park")));
\end{minted}

\subsection{构建集合：\texttt{collect}和\texttt{FromIterator}}\label{BuildColl}
在这本书中，我们曾多次看见使用\texttt{collect}方法来构建vector。例如，在\hyperref[ch02]{第2章}中，我们调用了\texttt{std::env::args()}来获取一个程序命令行参数的迭代器，然后调用了迭代器的\texttt{collect}方法来把它们收集到一个vector中：
\begin{minted}{Rust}
    let args: Vec<String> = std::env::args().collect();
\end{minted}

但\texttt{collect}并不是只能用于vector：事实上，它可以用于构建Rust标准库中的任意集合，只要迭代器产生合适的item类型：
\begin{minted}{Rust}
    use std::collections::{HashSet, BTreeSet, LinkedList, HashMap, BTreeMap};

    let args: HashSet<String> = std::env::args().collect();
    let args: BTreeSet<String> = std::env::args().collect();
    let args: LinkedList<String> = std::env::args().collect();

    // 收集map需要(key, value)对，因此在这个例子中，
    // 使用zip将字符串序列和整数序列绑定。
    let args: HashMap<String, usize> = std::env::args().zip(0..).collect();
    let args: BTreeMap<String, usize> = std::env::args().zip(0..).collect();

    // 等等
\end{minted}

当然，\texttt{collect}方法本身并不知道如何构建这些类型。当一些集合类型例如\texttt{Vec}或者\texttt{HashMap}知道如何从一个迭代器构建自身时，它会实现\texttt{std::iter::FromIterator} trait，\texttt{collect}只是它的便捷用法：
\begin{minted}{Rust}
    trait FromIterator<A>: Sized {
        fn from_iter<T: IntoIterator<Item=A>>(iter: T) -> Self;
    }
\end{minted}
如果一个集合类型实现了\texttt{FromIterator<A>}，那么它的类型关联函数\texttt{from\_iter}可以从一个产生\texttt{A}类型值的迭代器构建一个自身类型的集合。

在最简单的情况下，这个trait的实现可以只简单地构建一个空集合，然后把迭代器产生的item一个个添加进去。例如，\texttt{std::collections::LinkedList}的\texttt{FromIterator}实现就是按这种方式工作。

然而，一些方式可以有更好的实现。例如，从一个迭代器\texttt{iter}构造一个vector可以非常简单地实现：
\begin{minted}{Rust}
    let mut vec = Vec::new();
    for item in iter {
        vec.push(item);
    }
    vec
\end{minted}

但这并不是个好主意：随着vector的增长：它可能需要扩展缓冲区，需要调用堆分配器，还要拷贝现有元素。vector确实通过算法措施来保证这个开销很低，但如果有更简单的方式直接在最开始就分配一个正确大小的缓冲区，那么就完全没必要再次调整大小。

这就是迭代器的\texttt{Iterator} trait的\texttt{size\_hint}方法出现的原因：
\begin{minted}{Rust}
    trait Iterator {
        ...
        fn size_hint(&self) -> (usize, Option<usize>) {
            (0, None)
        }
    }
\end{minted}

这个方法返回迭代器可以产生的item数量的下界和一个可选的上界。默认的实现返回0作为下界，并拒绝指定上界，实际上就是在说“我不知道”，但很多迭代器可以做得更好。例如\texttt{Range}的迭代器就精确地知道它将产生多少个item，\texttt{Vec}和\texttt{HashMap}的迭代器也一样。这样的迭代器会提供自己的\texttt{size\_hint}的特化定义。

这两个界限正是\texttt{Vec}的\texttt{FromIterator}的实现所需要知道的信息，这样它就能从一开始就分配正确大小的缓冲区。插入新元素仍然会检查缓冲区是否足够大，因此即使提示不正确，也只会影响性能，而不会影响安全性。其他类型也可以选择类似的策略：例如，\texttt{HashSet}和\texttt{HashMap}也实现了\texttt{Iterator::size\_hint}来为哈希表选择合适的初始大小。

有关于类型推导的一个提示：在本节的开始处，同样的调用\texttt{std::env::args().collect()}根据上下文会产生四种不同类型的集合，这看起来可能有些奇怪。\texttt{collect}的返回值类型是它的类型参数，因此前两个调用等价于下面的调用：
\begin{minted}{Rust}
    let args = std::env::args().collect::<Vec<String>>();
    let args = std::env::args().collect::<HashSet<String>>();
\end{minted}

但如果\texttt{collect}的类型参数只有唯一一种可能，那么Rust会自动为你填充它。当你写出\texttt{args}的类型时，就是确保了这种情况。

\subsection{\texttt{Extend} trait}\label{extend}
如果一个类型实现了\texttt{std::iter::Extend} trait，那么它的\texttt{extend}方法可以把一个可迭代对象的item添加到集合中：
\begin{minted}{Rust}
    let mut v: Vec<i32> = (0..5).map(|i| 1 << i).collect();
    v.extend(&[31, 57, 99, 163]);
    assert_eq!(v, &[1, 2, 4, 8, 16, 31, 57, 99, 163]);
\end{minted}

所有的标准集合都实现了\texttt{Extend}，因此它们都有这个方法，就算是\texttt{String}也有。而数组和切片这种长度固定的集合没有这个方法。

这个trait的定义如下：
\begin{minted}{Rust}
    trait Extend<A> {
        fn extend<T>(&mut self, iter: T)
            where T: IntoIterator<Item=A>;
    }
\end{minted}
显然，这和\texttt{std::iter::FromIterator}非常相似：不过后者创建一个新集合，而\texttt{Extend}扩展一个已有集合。事实上，标准库中好几个类型的\texttt{FromIterator}实现都是简单地创建一个新的空集合，然后调用\texttt{extend}来填充它。例如，\texttt{std::collections::LinkedList}的\texttt{FromIterator}就是以这种方式工作：
\begin{minted}{Rust}
    impl<T> FromIterator<T> for LinkedList<T> {
        fn from_iter<I: IntoIter<Item = T>>(iter: I) -> Self {
            let mut list = Self::new();
            list.extend(iter);
            list
        }
    }
\end{minted}

\subsection{\texttt{partition}}
\texttt{partition}方法将一个迭代器的item分成两个集合，使用一个闭包来决定每个item属于哪个集合：
\begin{minted}{Rust}
    let things = ["doorknob", "mushroom", "noodle", "giraffe", "grapefruit"];

    // 一个令人震惊的事实：活物的名字都以奇数字母开头。
    let (living, nonliving): (Vec<&str>, Vec<&str>)
        = things.iter().partition(|name| name.as_bytes()[0] & 1 != 0);
    
    assert_eq!(living,    vec!["mushroom", "giraffe", "grapefruit"]);
    assert_eq!(nonliving, vec!["doorknob", "noodle"]);
\end{minted}

类似于\texttt{collect}，\texttt{partition}也可以创建任意类型的集合，不过两个集合的类型必须相同。类似于\texttt{collect}，你必须指明返回类型：上面的例子中写出了\texttt{living}和\texttt{nonliving}的类型并让类型推导选择合适的类型参数来调用\texttt{partition}。

\texttt{partition}的签名如下：
\begin{minted}{Rust}
    fn partition<B, F>(self, f: F) -> (B, B)
        where Self: Sized,
              B: Default + Extend<Self::Item>,
              F: FnMut(&Self::Item) -> bool;
\end{minted}
\texttt{collect}要求返回类型实现了\texttt{FromIterator}，而\texttt{partition}要求\texttt{std::default::Default}（所有的Rust集合都实现了它来返回一个空集合）和\texttt{std::default::Extend}。

其他语言提供把一个迭代器分成两个迭代器的\texttt{partition}操作，而不是构建两个集合。但这并不适合Rust：如果要实现分成两个迭代器，那么那些由底层迭代器产生但还未被分类后的迭代器产生的item必须被缓存；无论如何，最终都需要在内部构建某种类型的集合。

\subsection{\texttt{for\_each}和\texttt{try\_for\_each}}
\texttt{for\_each}方法简单地对每一个item应用一个闭包：
\begin{minted}{Rust}
    ["doves", "hens", "birds"].iter()
        .zip(["turtle", "french", "calling"].iter())
        .zip(2..5)
        .rev()
        .map(|((item, kind), quantity)| {
            format!("{} {} {}", quantity, kind, item)
        })
        .for_each(|gift| {
            println!("You have received: {}", gift);
        });
\end{minted}

这会打印出：
\begin{minted}{text}
    You have received: 4 calling birds
    You have received: 3 french hens
    You have received: 2 turtle doves
\end{minted}

它非常类似于一个简单的\texttt{for}循环，在循环中你还可以使用\texttt{break}和\texttt{countinue}控制语句。但使用\texttt{for}循环处理这种很长的链式适配器调用会有一点尴尬：
\begin{minted}{Rust}
    for gift in ["doves", "hens", "birds"].iter()
        .zip(["turtle", "french", "calling"].iter())
        .zip(2..5)
        .rev()
        .map(|((item, kind), quantity)| {
            format!("{} {} {}", quantity, kind, item)
        })
    {
        println!("You have received: {}", gift);
    }
\end{minted}

用于绑定的模式\texttt{gift}最终可能会距离使用它的循环体非常远。

如果你的闭包需要容错或者提前退出，你可以使用\texttt{try\_for\_each}：
\begin{minted}{Rust}
    ...
        .try_for_each(|gift| {
            writeln!(&mut output_file, "You have received: {}", gift)
        })?;
\end{minted}

\section{实现自己的迭代器}

你可以为自己的类型实现\texttt{IntoIterator}和\texttt{Iterator} trait，这样本章之前展示过的所有适配器和消耗器，还有其他可以和标准库迭代器接口协同工作的库和crate都可以使用。在本节中，我们将展示一个简单的范围类型的迭代器，然后展示一个更复杂的二叉树类型的迭代器。

假设我们有下面的范围类型（标准库的\texttt{std::ops::Range<T>}类型的简化）：
\begin{minted}{Rust}
    struct I32Range {
        start: i32,
        end: i32
    }
\end{minted}

迭代一个\texttt{I32Range}需要两个状态：当前的值和终点值。\texttt{I32Range}类型本身非常适合存储这两个状态：使用\texttt{start}作为下一个值，\texttt{end}作为终点。因此你可以这么实现\texttt{Iterator}：
\begin{minted}{Rust}
    impl Iterator for I32Range {
        type Item = i32;
        fn next(&mut self) -> Option<i32> {
            if self.start >= self.end {
                return None;
            }
            let result = Some(self.start);
            self.start += 1;
            result
        }
    }
\end{minted}
这个迭代器产生\texttt{i32} item，所以\texttt{i32}就是\texttt{Item}类型。如果迭代已经结束，\texttt{next}应该返回\texttt{None}；否则，它产生下一个值并更新当前的状态准备好下一次调用。

当然，\texttt{for}循环会使用\texttt{IntoIterator::into\_iter}来把操作数转换成迭代器。但标准库为每一个实现\texttt{Iterator}的类型自动提供了\texttt{IntoIterator}实现，因此\texttt{I32Range}已经可以使用：
\begin{minted}{Rust}
    let mut pi = 0.0;
    let mut numerator = 1.0;

    for k in (I32Range { start: 0, end: 14 }) {
        pi += numerator / (2*k + 1) as f64;
        numerator /= -3.0;
    }
    pi *= f64::sqrt(12.0);

    // IEEE 754标准指定了精确的结果。
    assert_eq!(pi as f32, std::f32::consts::PI);
\end{minted}

但\texttt{I32Range}是一种特殊情况，它的可迭代对象和迭代器恰好是同一种类型。很多情况并不是这么简单。例如，这里有一个\hyperref[ch10]{第10章}的二叉树类型：
\begin{minted}{Rust}
    enum BinaryTree<T> {
        Empty,
        NonEmpty(Box<TreeNode<T>>)
    }

    struct TreeNode<T> {
        element: T,
        left: BinaryTree<T>,
        right: BinaryTree<T>
    }
\end{minted}

经典的遍历二叉树的方法是递归，使用函数调用栈来追踪在树中的位置和已经访问过的节点。但当为\texttt{BinaryTree<T>}实现\texttt{Iterator}时，每一次\texttt{next}调用都必须产生一个值并且返回。为了追踪要产生的树节点，迭代器必须保持自己的栈。这里有一个\texttt{BinaryTree}的可能的迭代器类型：
\begin{minted}{Rust}
    use self::BinaryTree::*;

    // 中序遍历`BinaryTree`时的状态
    struct TreeIter<'a, T> {
        // 一个树节点的引用的栈。因为我们要使用`Vec`的
        // `push`和`pop`方法，栈的顶部是vector的尾部。
        //
        // 迭代器下一个要访问的节点在栈顶，
        // 那些还没访问的祖先节点在它下面。如果栈为空，
        // 就代表迭代结束了。
        unvisited: Vec<&'a TreeNode<T>>
    }
\end{minted}

当我们创建一个新的\texttt{TreeIter}时，它的初始状态应该是即将产生树中最左边的节点。根据\texttt{unvisited}栈的规则，它的栈顶应该是那个叶节点，再往下就是它的祖先节点：树中左侧边缘上的节点。我们可以从根节点访问左侧边缘一直到叶节点，把遇到的所有节点都入栈，来初始化\texttt{unvisited}，因此我们为\texttt{TreeIter}定义一个方法来实现这个过程：
\begin{minted}{Rust}
    impl<'a, T: 'a> TreeIter<'a, T> {
        fn push_left_edge(&mut self, mut tree: &'a BinaryTree<T>) {
            while let NonEmpty(ref node) = *tree {
                self.unvisited.push(node);
                tree = &node.left;
            }
        }
    }
\end{minted}

用\texttt{mut tree}可以让循环在遍历左侧边缘的过程中改变\texttt{tree}指向的节点，但因为\texttt{tree}是一个共享引用，所以它不能改变那些节点本身。

有了这个辅助方法，我们可以给\texttt{BinaryTree}一个\texttt{iter}方法来返回一个迭代树的迭代器：
\begin{minted}{Rust}
    impl<T> BinaryTree<T> {
        fn iter(&self) -> TreeIter<T> {
            let mut iter = TreeIter { unvisited: Vec::new() };
            iter.push_left_edge(self);
            iter
        }
    }
\end{minted}

\texttt{iter}方法先构造了一个\texttt{unvisited}栈为空的\texttt{TreeIter}，然后调用\texttt{push\_left\_edge}来初始化它。按照\texttt{unvisited}栈的规则，最左侧的节点在栈顶。

遵循标准库的实践，我们可以为二叉树的引用实现\texttt{IntoIterator}，然后在里面调用\texttt{BinaryTree::iter}：
\begin{minted}{Rust}
    impl<'a, T: 'a> IntoIterator for &'a BinaryTree<T> {
        type Item = &'a T;
        type IntoIter = TreeIter<'a, T>;
        fn into_iter(self) -> Self::IntoIter {
            self.iter()
        }
    }
\end{minted}

\texttt{IntoIter}定义将\texttt{TreeIter}设置为\texttt{\&BinaryTree}的迭代器类型。

最后，在\texttt{Iterator}的实现中，我们需要实际遍历这棵树。类似于\texttt{BinaryTree}的\texttt{iter}方法，迭代器的\texttt{next}方法也需要遵守栈的规则：
\begin{minted}{Rust}
    impl<'a, T> Iterator for TreeIter<'a, T> {
        type Item = &'a T;
        fn next(&mut self) -> Option<&'a T> {
            // 找到这一次迭代要产生的节点，
            // 或者结束迭代。（如果结果是`None`就通过
            // `?`运算符立即返回。）
            let node = self.unvisited.pop()?;

            // 在`node`之后，下一个产生的应该是`node`的右子树
            // 中的最左侧的节点，因此添加这条线上的节点。我们的辅助函数
            // 恰好就是我们需要的。
            self.push_left_edge(&node.right);

            // 产生这个节点的值的引用。
            Some(&node.element);
        }
    }
\end{minted}

如果栈为空，就表明迭代结束了。否则，\texttt{node}是现在要访问的节点的引用，这次调用会返回一个它的\texttt{element}字段的引用。但首先，我们必须把迭代器的状态更新到下一个节点。如果这个节点有一个右子树，那么下一个要访问的就是这棵子树中最左侧的节点，我们可以调用\texttt{push\_left\_edge}来添加它和它的未访问的祖先节点到栈里。但如果这个节点没有右子树，那么\texttt{push\_left\_edge}没有效果，这正是我们想要的：这时新的栈顶就是\texttt{node}的第一个未被访问的祖先节点。

有了\texttt{IntoIterator}和\texttt{Iterator}实现，我们最终可以使用一个\texttt{for}循环来迭代\texttt{BinaryTree}的引用。这里用到了\nameref{BinaryTree}中\texttt{BinaryTree}的\texttt{add}方法：
\begin{minted}{Rust}
    // 建造一棵小树。
    let mut tree = BinaryTree::Empty;
    tree.add("Jaeger");
    tree.add("robot");
    tree.add("droid");
    tree.add("mecha");

    // 迭代它。
    let mut v = Vec::new();
    for kind in &tree {
        v.push(*kind);
    }
    assert_eq!(v, ["droid", "Jaeger", "mecha", "robot"]);
\end{minted}

\hyperref[f15-1]{图15-1}展示了当我们遍历这棵树的过程中\texttt{unvisited}栈的行为。在每一次迭代中，下一个要被访问的节点都是栈顶，所有还未访问过的祖先节点都在它之下。

\begin{figure}[htbp]
    \centering
    \includegraphics[width=0.9\textwidth]{../img/f15-1.png}
    \caption{迭代二叉树}
    \label{f15-1}
\end{figure}

所有常用的迭代器适配器和消耗器都已经准备好在我们的树上使用：
\begin{minted}{Rust}
    assert_eq!(tree.iter()
               .map(|name| format!("mega-{}", name))
               .collect::<Vec<_>>(),
               vec!["mega-droid", "mega-jaeger",
                    "mega-mecha", "mega-robot"]);
\end{minted}

迭代器是Rust哲学的体现，即提供强大的、零成本、能提高代码的表现力和可读性的抽象。迭代器并不能完全替代循环，但它们提供了一种功能强大的原语，同时具有内建的惰性求值和高性能的特点。
